---
title: Agent
description: Feat AI Agent 功能介绍
sidebar:
    order: 4
---

import Mermaid from '../../../components/Mermaid.astro';

## 关于 Agent

Agent 是 Feat AI 框架中的一个重要组件，它基于 ReAct（Reasoning + Acting）范式，能够进行推理并执行动作。Agent 可以使用各种工具来完成复杂的任务，如文件操作、网络搜索、待办事项管理等。

:::note
在使用 Agent 之前，请确保已正确配置 Feat AI 模块并添加了相应的依赖。
:::

## 1. 快速开始

### 1.1 创建并运行 Agent

创建一个基本的 ReActAgent 实例并执行任务非常简单：

```java
import tech.smartboot.feat.ai.agent.ReActAgent;
import tech.smartboot.feat.ai.agent.FeatAgent;

// 创建一个 ReActAgent 实例
FeatAgent agent = new ReActAgent();

// 执行任务
String result = agent.execute("帮我搜索一下最新的 AI 技术发展趋势");
System.out.println(result);
```

有关完整示例，请参见 [ReActAgentTest.java](https://gitee.com/smartboot/feat/blob/master/feat-ai/src/test/java/tech/smartboot/feat/ai/agent/ReActAgentTest.java)

### 1.2 配置 Agent 选项

在创建 Agent 时，您可以配置各种选项以满足特定需求：

```java
import tech.smartboot.feat.ai.agent.ReActAgent;
import tech.smartboot.feat.ai.agent.AgentOptions;
import tech.smartboot.feat.ai.chat.ChatModelVendor;

// 创建 Agent 配置
AgentOptions options = AgentOptions.create()
    .maxIterations(15)                         // 设置最大推理迭代次数
    .chatOptions()
    .model(ChatModelVendor.GiteeAI.DeepSeek_V32_EXP); // 设置使用的模型

// 创建 Agent 实例
ReActAgent agent = new ReActAgent();
agent.options.maxIterations(15)
    .chatOptions()
    .model(ChatModelVendor.GiteeAI.DeepSeek_V32_EXP);
```

## 2. 核心概念

### 2.1 ReAct 范式

ReAct 是一种结合推理（Reasoning）和行动（Acting）的范式，使 Agent 能够：

1. **思考（Thought）** - 分析当前情况和目标
2. **行动（Action）** - 执行具体的操作
3. **观察（Observation）** - 获取行动结果并据此继续推理

这种循环往复的过程让 Agent 能够解决复杂的多步骤任务。

<Mermaid code={`
graph TD
    A[开始] --> B[思考]
    B --> C[执行动作]
    C --> D[观察结果]
    D --> E{是否完成?}
    E -->|否| B
    E -->|是| F[返回最终答案]
`}/>

### 2.2 Agent 状态

Agent 在执行过程中会经历以下状态：

- **IDLE** - 空闲状态
- **RUNNING** - 正在运行
- **TOOL_EXECUTION** - 正在执行工具
- **FINISHED** - 执行完成
- **ERROR** - 执行出错

可以通过 [getState()](file:///Users/zhengjw22mac123/IdeaProjects/feat/feat-ai/src/main/java/tech/smartboot/feat/ai/agent/ReActAgent.java#L301-L303) 方法获取 Agent 的当前状态：

```java
AgentState state = agent.getState();
System.out.println("当前状态: " + state);
```

## 3. 内置工具

Feat AI Agent 内置了多种常用工具，在 ReActAgent 构造函数中默认注册：

### 3.1 待办事项工具 (TodoListTool)

管理待办事项列表：

```json
// 创建待办事项列表
Action: todo_list
Action Input: {
  "action": "create"
}

// 添加待办事项
Action: todo_list
Action Input: {
  "action": "add",
  "list_id": "todo_list_1234567890",
  "title": "完成项目文档",
  "description": "编写 Feat AI 的使用文档"
}

// 列出所有待办事项
Action: todo_list
Action Input: {
  "action": "list",
  "list_id": "todo_list_1234567890"
}

// 完成待办事项
Action: todo_list
Action Input: {
  "action": "complete",
  "list_id": "todo_list_1234567890",
  "item_id": 1
}

// 移除待办事项
Action: todo_list
Action Input: {
  "action": "remove",
  "list_id": "todo_list_1234567890",
  "item_id": 1
}
```

### 3.2 文件操作工具 (FileOperationTool)

执行文件系统操作：

```json
// 列出目录内容
Action: file_operation
Action Input: {
  "action": "list_directory",
  "path": "./",
  "recursive": false
}

// 读取文件
Action: file_operation
Action Input: {
  "action": "read_file",
  "path": "./README.md"
}

// 写入文件
Action: file_operation
Action Input: {
  "action": "write_file",
  "path": "./output.txt",
  "content": "这是写入的内容"
}

// 创建目录
Action: file_operation
Action Input: {
  "action": "create_directory",
  "path": "./new_directory"
}

// 删除文件
Action: file_operation
Action Input: {
  "action": "delete_file",
  "path": "./unwanted.txt"
}

// 检查文件是否存在
Action: file_operation
Action Input: {
  "action": "file_exists",
  "path": "./important.txt"
}
```

### 3.3 搜索工具 (SearchTool)

执行网络搜索：

```json
// 使用百度搜索
Action: search
Action Input: {
  "query": "最新的 AI 技术发展趋势",
  "engine": "baidu",
  "max_results": 5
}

// 使用必应搜索
Action: search
Action Input: {
  "query": "最新的 AI 技术发展趋势",
  "engine": "bing",
  "max_results": 5
}
```

### 3.4 网页阅读工具 (WebPageReaderTool)

读取网页内容：

```json
// 读取网页
Action: web_page_reader
Action Input: {
  "url": "https://example.com/article"
}
```

### 3.5 子 Agent 工具 (SubAgentTool)

创建子 Agent 来处理特定任务：

```json
// 创建子 Agent
Action: sub_agent
Action Input: {
  "agent_name": "analysis_agent",
  "task": "分析这份报告的主要观点"
}
```

## 4. 自定义工具

除了内置工具外，您还可以创建自定义工具来扩展 Agent 的功能：

```java
import tech.smartboot.feat.ai.agent.AgentTool;
import com.alibaba.fastjson2.JSONObject;

public class CustomTool implements AgentTool {
    
    @Override
    public String execute(JSONObject parameters) {
        // 实现工具的具体逻辑
        return "工具执行结果";
    }
    
    @Override
    public String getName() {
        return "custom_tool";
    }
    
    @Override
    public String getDescription() {
        return "这是一个自定义工具";
    }
    
    @Override
    public String getParametersSchema() {
        // 返回参数定义的 JSON Schema
        return "{\n" +
               "  \"type\": \"object\",\n" +
               "  \"properties\": {\n" +
               "    \"param1\": {\"type\": \"string\"}\n" +
               "  }\n" +
               "}";
    }
}

// 注册自定义工具
AgentOptions options = AgentOptions.create();
options.addTool(new CustomTool());
```

## 5. 内存管理和提示模板

### 5.1 内存管理

Agent 具有内存管理功能，可以存储和检索相关信息：

```java
import tech.smartboot.feat.ai.agent.memory.AgentMemory;
import tech.smartboot.feat.ai.agent.memory.DefaultAgentMemory;

// 创建自定义内存管理器
AgentMemory memory = new DefaultAgentMemory();
AgentOptions options = AgentOptions.create()
    .memory(memory);

// 或者在创建 Agent 时配置
ReActAgent agent = new ReActAgent();
```

内存管理配置选项：

| 选项 | 描述 | 默认值 |
|------|------|--------|
| memory | Agent 记忆实例 | DefaultAgentMemory |
| enableSmartMemory | 是否启用智能记忆检索 | true |
| memoryRetrievalThreshold | 记忆检索阈值 | 0.5 |
| maxMemoryRetrievalCount | 最大记忆检索数量 | 5 |
| maxIterations | 最大推理迭代次数 | 20 |

### 5.2 提示模板

Agent 使用提示模板来引导 AI 模型的行为。默认使用 `feat_react_agent.tpl` 模板，其中包含了以下变量：

- `{{tool_descriptions}}` - 所有工具的描述信息
- `{{tool_names}}` - 所有工具名称列表
- `{{date}}` - 当前日期时间
- `{{history}}` - 历史对话记录
- `{{input}}` - 用户输入的任务
- `{{agent_scratchpad}}` - Agent 的推理过程记录

## 6. 完整示例和最佳实践

以下是一个完整的使用示例：

```java
import tech.smartboot.feat.ai.agent.ReActAgent;
import tech.smartboot.feat.ai.agent.FeatAgent;

public class AgentDemo {
    public static void main(String[] args) {
        // 创建 Agent 实例
        FeatAgent agent = new ReActAgent();
        
        // 执行任务
        String result = agent.execute("请帮我调研一下 AI 领域的最新进展，并整理成一份简要报告");
        System.out.println("任务结果:");
        System.out.println(result);
    }
}
```

有关完整示例，请参见 [ReActAgentTest.java](https://gitee.com/smartboot/feat/blob/master/feat-ai/src/test/java/tech/smartboot/feat/ai/agent/ReActAgentTest.java)

### 最佳实践

1. **合理设置迭代次数** - 根据任务复杂度设置合适的最大迭代次数，避免无限循环
2. **选择合适模型** - 根据任务需求选择具有相应能力的模型
3. **工具组合使用** - 合理组合不同工具以完成复杂任务
4. **监控 Agent 状态** - 通过状态监控了解 Agent 的执行过程
5. **错误处理** - 妥善处理执行过程中可能出现的异常情况